posted 08-22-2001 06:34 PM           

const char *path: String reflecting a directory.
const char *extension: File extension to list (incluing a leading period).
char *listbuf: Pointer to a buffer to fill.
int bufsize: Length of the buffer.

posted 08-22-2001 06:36 PM           

int color:
int numPoints:
vec3_t *points:

?

D!ABLO:
creates a solid coloured permanent polygon in the renderer (and world) based on the given array of vertices/points.
it returns a reference handle to the polygon as it appears in the renderlist.
this function should be disabled, but it may still work.

posted 08-22-2001 06:36 PM           

int id: a value previously returned by trap_DebugPolygonCreate

D!ABLO:
removes a polygon that was previously created via trap_DebugPolygonCreate.

posted 08-22-2001 06:42 PM           

float *v:Vector to snap.

posted 08-22-2001 08:05 PM          

qtime_t *qtime: Point in time - look at q_shared.h qtime_t for details.

Returns current system time and date at server.

posted 09-01-2001 06:54 PM           

arg0 - the name of the .RoQ file to load.

xpos - the X coordinate on-screen for the left edge of the cinematic display.

ypos - the Y coordinate on-screen for the top edge of the cinematic display.

width - the screen width of the cinematic display.

height - the screen height of the cinematic display.

bits - combinations of the following flags:

posted 09-01-2001 07:14 PM           

handle - the handle returned by a previous call to trap_CIN_PlayCinematic

posted 09-01-2001 07:16 PM           

handle a handle returned by a previous call to trap_CIN_PlayCinematic

posted 09-01-2001 07:18 PM           

handle - a handle returned by a previous call to trap_CIN_PlayCinematic

posted 09-01-2001 07:20 PM           

handle - a handle returned by a previous call to trap_CIN_PlayCinematic

x - the new X coordinate on-screen of the left edge of the cinematic.

y - the new Y coordinate on-screen of the top edge of the cinematic.

w - the new width on-screen of the cinematic.

h - the new height on-screen of the cinematic.

posted 09-15-2001 05:43 PM           

var_name: name of cvar (console variable).
buffer: destination string buffer.
bufsize: maximum limit of string buffer.

This trap copies the content of a cvar named by var_name into a mod-space string. This is useful for obtaining cvar contents that are not bound, or cannot be bound, to a vmCvar_t variable in the mod code.

The terminating NULL is attached to the end of the copied string by this trap, guaranteeing buffer holds a null-terminated string. The total number of characters copied, including terminating NULL, fits within the size specified by bufsize, truncating the string if necessary.

A nonexistent cvar provides an empty string. An existing cvar with empty content also provides an empty string. Thus, this trap is not sufficient to determine if a cvar actually exists or not.

This trap does not create a new cvar; to create a new cvar during run-time, you can use trap_Cvar_Set or trap_SendConsoleCommand.

posted 02-16-2002 04:11 PM           

exec_when: When to execute command: EXEC_NOW, EXEC_INSERT, EXEC_APPEND
text: Console command to run.

The string provided by text is run as if typed as a command into the console. A leading slash (/) is not required.

Description of the EXEC_* values are described in q_shared.h.

In general, EXEC_APPEND is the most common use, simulating the user typing in the command. The string is stored to a buffer (appended) until a game frame is completed, then the engine will examine the buffered strings to run.

EXEC_NOW is a bad idea, as it can lead to an infinite loop: EXEC_NOW causes an immediate jump into engine space, which then jumps back to QVM/mod space to execute commands, which could lead to an immediate jump right back to engine space, which would lead to... and so on.

Useless examples:

trap_SendConsoleCommand(EXEC_APPEND, "team free");
trap_SendConsoleCommand(EXEC_APPEND, "say Vini vidi vici.; quit");

[PS]OK, so Timbo already did this, but I was looking at the CGAME's list, which didn't have this one crossed out. [/PS]

posted 02-16-2002 04:26 PM           

cmdName: Command name.

The string cmdName is added to a tab-completion list for the console. Tab completion is case-insensitive, but the completed string is rewritten with the stored capitalization.

posted 02-16-2002 05:21 PM           

s: Command string

Sends command string as a client command directly to server. In contrast, trap_SendConsoleCommand() sends the string to the local console first, and, if not recognized there, sends to the server as a client command.

This trap makes no distinction among EXEC_NOW, EXEC_INSERT, or EXEC_APPEND as with trap_SendConsoleCommand(), since the command is sent "somewhere else".

The set of "client commands" is separate from "console commands", so that a misbehaving client cannot kill a server by attempting to send "quit" as a command.

posted 02-16-2002 05:40 PM           

keynum: A key keynum

Returns true is the indicated key is held down, returns false if not held down (released).

The values of keynum range from 0 to 255, inclusive. For the most part, a key's keynum corresponds to its character's ASCII value (e.g. the 'A' key is 65).

I have a list of keynames used by the bind command with their keynums which I may append at a later date. In the meantime, if you want to know them now, you can do this:

Create a keynums.cfg with a pattern like:
bind 0x00 Key 0x00
bind 0x01 Key 0x01
...
bind 0xfe Key 0xfe
bind 0xff Key 0xff

(case matters for the hex values, and a scripting language to automate this really helps)

Back up your q3config.cfg, run Q3, "/exec keynums.cfg; bindlist; condump keynums.txt; quit"

In the file "keynums.txt" you should now have lines like:
UPARROW "Key 0x84"

There's your keynum list.

posted 02-16-2002 05:55 PM           

catcher: Key catchers bitmask

Redirects key events to different module(s).

Normally, key events are interpreted by the engine, affected by the key bindings. This trap allows you redirect key events to other components.

Valid catchers are:
KEYCATCH_CONSOLE: the console
KEYCATCH_UI: the ui module
KEYCATCH_MESSAGE: the little message editor thingy
KEYCATCH_CGAME: the cgame module

These are bitmasked values, meaning you can combine them with the OR operator (|), as in (KEYCATCH_UI|KEYCATCH_CGAME), but I recommend against trying multiple catchers (it may get confusing).

As a mods programmer, you may be most interested in KEYCATCH_CGAME, and on this I will concentrate this entry.

--- The Keyboard ---

When key-catching is enabled (trap_Key_SetCatcher(KEYCATCH_CGAME);), upon a change in key state (gets pressed or gets released), the engine calls the vmMain() function in cg_main.c with the following parameters:
command = CG_KEY_EVENT
arg0 = keynum
arg1 = 1 if pressed, 0 if released.

In baseq3 game source, this event is already handled and delegated to CG_KeyEvent(), which is empty.

The values for keynum are the same as for trap_Key_IsDown().

Key catching is disabled by calling with a parameter of 0 (as in, no catchers). Key catching is also terminated if the user presses the ESC key, which means you won't receive events on the ESC key.

--- The Mouse ---

When key-catching is enabled, mouse movement is also redirected to the specified module. When the engine detects mouse movement, it calls vmMain() with the following parameters:
command = CG_MOUSE_EVENT
arg0 = relative X position
arg1 = relative Y position

The game source for baseq3 delegates this event to CG_MouseEvent().

Pointer Device Movement - Reported Value:
Left - Negative X
Right - Positive X
Up - Negative Y
Down - Positive Y

The engine only reports mouse movement -- if the mouse doesn't move, there is no mouse event. The engine reports mouse buttons and wheels (if any) as key events, for binding purposes.

Cvars do not influence the reported values.

posted 02-16-2002 06:00 PM           

(no parameters)

Returns a bitmask representing active key catchers.

Bitmask values are:
KEYCATCH_CONSOLE
KEYCATCH_UI
KEYCATCH_MESSAGE
KEYCATCH_CGAME

(see also trap_Key_SetCatcher())

posted 02-16-2002 06:04 PM           

binding: command string presumably bound to a key.

Returns keynum of the key that has the binding specified by binding. Case-sensitive.

posted 02-17-2002 02:28 AM           

cmdName: command name

Although this trap is not actually used anywhere in baseq3 game source, a reasonable assumption, based on function name and parameters, is that this trap removes a command name from the list of command completions. That is, the inverse of trap_AddCommand().

posted 02-27-2002 10:06 AM          

int color:
int numPoints:
vec3_t *points:

?

D!ABLO:
creates a solid coloured permanent polygon in the renderer (and world) based on the given array of vertices/points.
it returns a reference handle to the polygon as it appears in the renderlist.
this function should be disabled, but it may still work.

posted 06-28-2002 11:20 PM           

gentity_t* ent : The entity to apply the collision map to.

const char* name : The name of the brush model. If the model is inline (built into the map) it will "*0", "*1", "*n". These names are generated by the map compiler and cannot be changed. "*0" is always the map itself. If the model is external to the map then it is the filename of the BSP (another map is technically valid as a stand-alone model though it is not externally lit and all external surfaces are backfaced culled).

This function does several special things to an entity which should not be done any other way.

posted 09-28-2002 03:54 AM           

const vec3_t org: origin of the light - where the light will be.

float intensity: not the exact intensity of the light, but the radius of the light - the light is a sphere-like object and points within that object are lighted up, and the closer something is to the origin of the light (org) the closer the light will be to the actual colour data of the light.

float r/g/b: this is the colour data of the light (normalized, so the highest value, 255, is 1.0) - r is the amount of red light, g green light, and b blue light.

This function will add a light to the game at org, which has a radius of intensity units, and the colour data which is shown in the variables r, g, and b. The highest number for an RGB index is 255, but in Quake 3 the colour's index is divided by 255 to give a normalized value.

Say I want to make a purple light. The colour data for purple in RGB is 255,0,255. So the normalized values for this colour are:

255/255 = 1.0
0/255 = 0.0
255/255 = 1.0

So to add a purple light at the vector x, and radius 2.4 I would write:

trap_R_AddLightToScene( x, 2.4, 1.0, 0.0, 1.0 );

posted 09-28-2002 04:08 AM           

const char *name: pointer to the name of the shader (?)

posted 05-24-2003 05:36 PM          

cg_local.h says:
// force a screen update, only used during gamestate load
void trap_UpdateScreen( void );

the Trap_UpdateScreen itself appears to be:
cg_syscalls.c
void trap_UpdateScreen( void ) {
syscall( CG_UPDATESCREEN );
}

This is also called by:
UI_Atoms.C

void UI_UpdateScreen( void ) {
trap_UpdateScreen();
}

it is also called by:
ui_local.h
void trap_R_DrawStretchPic( float x, float y, float w, float h, float s1, float t1, float s2, float t2, qhandle_t hShader );
void trap_UpdateScreen( void );
int trap_CM_LerpTag( orientation_t *tag, clipHandle_t mod, int startFrame, int endFrame, float frac, const char *tagName );

The locations of the calls and the remarks placed around it imply that this trap is ONLY for updating the screen during connection to local or remote host.

(eg: Loading....shotgun ; Loading.... Gauntlet ect... during the load of a map.)

posted 07-03-2003 01:58 AM          

Allocates a free client slot and returns the client number. Also marks the client as bot in the engine (arg2 will be 1 when a GAME_CLIENT_CONNECT message is dispatched to vmMain for this client).